/**
 * The player, provides the functionality of comparing a guess and storing all
 * the information that a player would know. his/her score, # of wins, and their
 * secret word.
 * 
 * @author Brian
 * 
 */
public interface Player {

	/**
	 * Sets the players secret word.
	 * 
	 * @requires The word is in the dictionary
	 * @ensures The players secret word is assigned to the correct value.
	 * @param word the word to be set
	 * @throws WordException exception passed to controller
	 */
	void setWord(String word) throws WordException;

	/**
	 * returns the current score of a player.
	 * 
	 * @requires true
	 * @ensures the score of the player is returned
	 * @return int the amount of points a player has
	 */
	int getScore();

	/**
	 * keeps track of the wins and score for the player. sets the players score
	 * to accurately represent the players score
	 * 
	 * @requires true
	 * @ensures Score is added to the players running total and their win tally
	 *          goes up by one
	 * @param score
	 *            the score to be addded
	 */
	void win(int score);

	/**
	 * keeps track of the score for the loser of a round.
	 * 
	 * @requires true
	 * @ensures Score is added to the players running total
	 * @param score
	 *            the score to be added
	 */
	void lose(int score);

	/**
	 * A guess against the player is compared to the secret word with a given
	 * dictionary.
	 * 
	 * @requires player has a secret word
	 * @ensures compares the value of the guess and the secret word and returns
	 *          the integer value of correct characters.
	 * @return boolean value of if the guess is correct or not
	 * @param sharedLetters
	 *            integer array holding sharedLetters
	 * @param guess
	 *            the guess that must be compared
	 * @throws WordException passes exception to controller
	 */
	boolean guess(String guess, int[] sharedLetters) throws WordException;

	/**
	 * Resets the values of the player to start a completely new game.
	 * 
	 * @requires true
	 * @ensures the players values are reset to their original representation
	 */
	void reset();

	/**
	 * retrieves the # of wins a player has.
	 * 
	 * @requires true
	 * @ensures the number of wins be returned
	 * @return int # of wins
	 */
	int getWins();

}
